COMMENT ⊗   VALID 00002 PAGES
C REC  PAGE   DESCRIPTION
C00001 00001
C00002 00002	This is the description of MacLisp NEWIO for TOPS-10 and SAIL versions
C00010 ENDMK
C⊗;
This is the description of MacLisp NEWIO for TOPS-10 and SAIL versions
of that language. Since the author is most familiar with the SAIL version,
the features will be described from the point of view of a SAIL user. However,
in all places where this is different than what a TOPS-10 person would see,
this difference will be noted.

⊂IO⊃

In MacLisp, one is often interested in doing input/output to and from
disk files and the TTY (terminal). Other physical devices are usually
available on the machine, but these are the main ones for most people. 

On a disk, units of information are called "files". Each file is located
on a "directory". Simply stated, a user of the system has a directory which
contains files. Normally files contain text or some representation of a program.
People want to edit or change the contents of the files, add new files, and
delete existing ones. The operating system normally provides commands and
programs to accomplish these ends, but it is nice for user programs to be
able to do these tasks also.


In MacLisp primitives are provided to allow such programs to be written.
This short description of NEWIO will describe these primitives and
some sample programs that show the use of these primitives.

⊂Opening Files⊃

The first thing that you will need  is to "OPEN" a file that you are interested
in changing, reading, or creating. OPENing a file means that you are
informing the MacLisp and operating system that you need a "channel" to
perform input or output on as well as indicating the things you will be
doing with that channel. For instance, consider the simple case of
reading a disk file which contains some s-expressions that you want to
process; suppose the file is called SEXPR.LSP and is located on the directory
of LO,SER (this is a SAIL type PPN; a TOPS-10 PPN would be something like
120,712). You open the file by saying:

	(OPEN '((DSK (LO SER)) SEXPR LSP) '(IN ASCII))

This opens he file for INput in ASCII or text style mode. This means that the
file contains ASCII coded information. This will return a channel pointer such as:

	#FILE-IN-|DSK:SEXPR.LSP[LO,SER]|-7774 

On the SAIL system, the function EOPEN will skip over the E directory
page if there is one.

The IO functions that can now be performed with wrt a file open for reading
are, essentially, READ, TYI, and TYIPEEK.

READ can take up to 2 arguments and are interpreted as follows:

	(READ) reads one s-expression from the default input source. This
source is determined from the value of the variable INFILE, which will be
discussed later.

	(READ f) reads one s-expression from the file f. F is a channel pointer
like that shown above. 

	(READ f x) reads one s-expression from the file f and returns x if an
end of file is encountered while doing the READ. An end of file means that
no more text is in the file that is being read. 

	(READ x f) same as above.

A standard practice is something like:

 	((lambda (file eof)
		 (do ((form (read file eof)(read file eof)))
		     ((eq form eof) (end-of-file file))
		     (process-form form)))
	 (open '((dsk (lo ser)) sexpr lsp)) (ncons ()))  

which opens a file and processes each form in it until an end of file
happens, at which time it calls the end of file handler.

Similarly, TYI takes the same arguments as READ but returns the ascii code
for the next character in the file specified.

	(TYI) inputs one character from the default input source

	(TYI f) inputs one character from f

	(TYI f n) inputs one character from f and returns the fixnum n if
an end of file is encountered.

TYIPEEK takes up to three arguments. The first tells the type of peeking that
is done. (This should be looked up in the Moonual or in LISPARC) The normal mode
has NIL as it's first argument (the default if no arguments is supplied is nil
for each).

	(TYIPEEK) returns the ascii code for the next character in the
default input source.

	(TYIPEEK () f) peeks at the next character from f

	(TYIPEEK f n) peeks at the next character from f and returns the fixnum 
n if an and of file is encountered. If n is not given, as above, then -1 is returned
in this case.

On the output side, one can open a file for output of ASCII characters with

	(open '((dsk (lo ser)) out put) '(out ascii))

Then the output can be done with:

	(PRINT e f) output the expression e to the file f

	(PRIN1 e f) as above

	(PRINC e f) as above

	(TYO n f) output the ASCII code, n, to f

⊂File Names⊃

In NEWIO the file names are of the form:

	((DEV (P PN)) FILE EXT)

which corresponds to the OLDIO form:

	(FILE EXT DEV (P PN))

The function, DEFAULTF, will take a file name in the OLDIO form and convert it
to NEWIO form. In general, DEFAULTF will take a file specification and
"merge" it with the default form to create the actual file specification,
performing the canonicalization above. 
		(DEFUN DEFAULTF (X)
		       (SETQ DEFAULTF
			     (MERGEF (OR X DEFAULTF) DEFAULTF)))